home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-desktop-9.10-i386-PL.iso / casper / filesystem.squashfs / usr / lib / perl5 / Text / Iconv.pm < prev   
Encoding:
Perl POD Document  |  2007-10-17  |  4.9 KB  |  161 lines
  1. package Text::Iconv;
  2. # @(#) $Id: Iconv.pm,v 1.10 2007/10/17 14:14:22 mxp Exp $
  3. # Copyright (c) 2007 Michael Piotrowski
  4.  
  5. use strict;
  6. use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
  7.  
  8. require Exporter;
  9. require DynaLoader;
  10. require AutoLoader;
  11.  
  12. @ISA = qw(Exporter AutoLoader DynaLoader);
  13. # Items to export into callers namespace by default. Note: do not export
  14. # names by default without a very good reason. Use EXPORT_OK instead.
  15. # Do not simply export all your public functions/methods/constants.
  16. @EXPORT_OK = qw(
  17.     convert
  18. );
  19. $VERSION = '1.7';
  20.  
  21. bootstrap Text::Iconv $VERSION;
  22.  
  23. # Preloaded methods go here.
  24.  
  25. # Autoload methods go after =cut, and are processed by the autosplit program.
  26.  
  27. 1;
  28. __END__
  29. # Below is the documentation for the module.
  30.  
  31. =head1 NAME
  32.  
  33. Text::Iconv - Perl interface to iconv() codeset conversion function
  34.  
  35. =head1 SYNOPSIS
  36.  
  37.   use Text::Iconv;
  38.   $converter = Text::Iconv->new("fromcode", "tocode");
  39.   $converted = $converter->convert("Text to convert");
  40.  
  41. =head1 DESCRIPTION
  42.  
  43. The B<Text::Iconv> module provides a Perl interface to the iconv()
  44. function as defined by the Single UNIX Specification.
  45.  
  46. The convert() method converts the encoding of characters in the input
  47. string from the I<fromcode> codeset to the I<tocode> codeset, and
  48. returns the result.
  49.  
  50. Settings of I<fromcode> and I<tocode> and their permitted combinations
  51. are implementation-dependent.  Valid values are specified in the
  52. system documentation; the iconv(1) utility should also provide a B<-l>
  53. option that lists all supported codesets.
  54.  
  55. =head2 Utility methods
  56.  
  57. B<Text::Iconv> objects also provide the following methods:
  58.  
  59. retval() returns the return value of the underlying iconv() function
  60. for the last conversion; according to the Single UNIX Specification,
  61. this value indicates "the number of non-identical conversions
  62. performed."  Note, however, that iconv implementations vary widely in
  63. the interpretation of this specification.
  64.  
  65. This method can be called after calling convert(), e.g.:
  66.  
  67.   $result = $converter->convert("lorem ipsum dolor sit amet");
  68.   $retval = $converter->retval;
  69.  
  70. When called before the first call to convert(), or if an error occured
  71. during the conversion, retval() returns B<undef>.
  72.  
  73. get_attr(): This method is only available with GNU libiconv, otherwise
  74. it throws an exception.  The get_attr() method allows you to query
  75. various attributes which influence the behavior of convert().  The
  76. currently supported attributes are I<trivialp>, I<transliterate>, and
  77. I<discard_ilseq>, e.g.:
  78.  
  79.   $state = $converter->get_attr("transliterate");
  80.  
  81. See iconvctl(3) for details.  To ensure portability to other iconv
  82. implementations you should first check for the availability of this
  83. method using B<eval {}>, e.g.:
  84.  
  85.     eval { $conv->get_attr("trivialp") };
  86.     if ($@)
  87.     {
  88.       # get_attr() is not available
  89.     }
  90.     else
  91.     {
  92.       # get_attr() is available
  93.     }
  94.  
  95. This method should be considered experimental.
  96.  
  97. set_attr(): This method is only available with GNU libiconv, otherwise
  98. it throws an exception.  The set_attr() method allows you to set
  99. various attributes which influence the behavior of convert().  The
  100. currently supported attributes are I<transliterate> and
  101. I<discard_ilseq>, e.g.:
  102.  
  103.   $state = $converter->set_attr("transliterate");
  104.  
  105. See iconvctl(3) for details.  To ensure portability to other iconv
  106. implementations you should first check for the availability of this
  107. method using B<eval {}>, cf. the description of set_attr() above.
  108.  
  109. This method should be considered experimental.
  110.  
  111. =head1 ERRORS
  112.  
  113. If the conversion can't be initialized an exception is raised (using
  114. croak()).
  115.  
  116. =head2 Handling of conversion errors
  117.  
  118. I<Text::Iconv> provides a class attribute B<raise_error> and a
  119. corresponding class method for setting and getting its value.  The
  120. handling of errors during conversion depends on the setting of this
  121. attribute.  If B<raise_error> is set to a true value, an exception is
  122. raised; otherwise, the convert() method only returns B<undef>.  By
  123. default B<raise_error> is false.  Example usage:
  124.  
  125.   Text::Iconv->raise_error(1);     # Conversion errors raise exceptions
  126.   Text::Iconv->raise_error(0);     # Conversion errors return undef
  127.   $a = Text::Iconv->raise_error(); # Get current setting
  128.  
  129. =head2 Per-object handling of conversion errors
  130.  
  131. As an experimental feature, I<Text::Iconv> also provides an instance
  132. attribute B<raise_error> and a corresponding method for setting and
  133. getting its value.  If B<raise_error> is B<undef>, the class-wide
  134. settings apply.  If B<raise_error> is 1 or 0 (true or false), the
  135. object settings override the class-wide settings.
  136.  
  137. Consult L<iconv(3)> for details on errors that might occur.
  138.  
  139. =head2 Conversion of B<undef>
  140.  
  141. Converting B<undef>, e.g.,
  142.  
  143.   $converted = $converter->convert(undef);
  144.  
  145. always returns B<undef>.  This is not considered an error.
  146.  
  147. =head1 NOTES
  148.  
  149. The supported codesets, their names, the supported conversions, and
  150. the quality of the conversions are all system-dependent.
  151.  
  152. =head1 AUTHOR
  153.  
  154. Michael Piotrowski <mxp@dynalabs.de>
  155.  
  156. =head1 SEE ALSO
  157.  
  158. iconv(1), iconv(3)
  159.  
  160. =cut
  161.